Node / mirrors / micropython-reticulum rns://a9593d0a1ff565aefd8594cbdb671af6/mirrors/micropython-reticulum

Mirrored from https://github.com/varna9000/micropython-reticulum.git synced 10h ago

🗀 Files • ☸ Work (0) • 🖹 Commits (126) • ⑃ Branches (2) • ⌆ Tags (0) • ♥ Thanks (2) • 🗠 Stats

Each row below is a working example in the T383838firmware/ folder. Pick the one closest to what you want, then follow the matching walkthrough further down.

If you only install one, install MeshChat — your node will appear in its peer list within a few seconds of booting on the same LAN.

You have two choices of firmware. Pick the one that matches what you want to build:

Commands are case-insensitive. The same pattern can drive relays, motors, or any GPIO-attached hardware — see the gpio_control peripheral.

Serves micron-format pages over Reticulum Links. Think of it as a tiny web server reachable only via Reticulum.

• Hardware: any supported ESP32-S3 board. Optional sensors connected via I²C, UART, or ADC.

• Firmware: standard MicroPython.

• Config: WiFi (or LoRa / TCP) interface enabled.

• How to use: open NomadNet or MeshChat on another machine, wait for the announce as T383838nomadnetwork.node, then browse to the node. The default landing page is T383838firmware/pages/index.mu. Drop more T383838.mu files into T383838firmware/pages/ to add more pages.

Template variables you can use inside a T383838.mu page:

Pages under ~417 bytes ride a single encrypted link packet. Larger pages and downloadable files (up to 16 KB) are transferred automatically via the Resource protocol. Files dropped into T383838firmware/files/ are served at T383838/file/<name> — link to them from a page with BT383838 [label:/file/name] .

Captures a photo with an OV2640 and ships it back as an LXMF image attachment. By

default it sends a VGA (640 × 480) WebP (~7 KB) — small enough for LoRa yet far

higher resolution than a same-size JPEG — and falls back to JPEG if the WebP encoder

isn't installed.

!camera demo

• Hardware: an ESP32-S3-CAM board with an OV2640 camera + PSRAM.

• Firmware: camera-enabled MicroPython is mandatory (see Step 1). Standard MicroPython will fail at T383838import camera.

• Config: WiFi creds.

• How to use: send T383838image from MeshChat / Sideband to get a photo back (delivered via a Link + Resource transfer). Send T383838help or T383838settings to see the live controls.

• Image format & quality: resolution, WebP quality, downscale, exposure, flash and night mode are all adjustable at runtime by messaging the node — see Camera image settings (JPEG & WebP) for every parameter and the size/quality trade-offs.

• WebP encoder: the optional native module T383838webp_fast.mpy in T383838/lib (built from tools/natmod/webp_fast/). Without it the node simply sends JPEG. Note: builds before July 2026 swapped red/blue in every image (pink skies, blue foliage) — a BGR/RGB mismatch in the JPEG decoder, since fixed; update T383838/lib/webp_fast_xtensawin.mpy if your photos look like that.

For direct (non-LXMF) capture you can also use the peripheral module from the REPL:

T282828

Tff7b72from T7ee787peripheralsT7ee787.T7ee787camera Tff7b72import Te6edf3capture

T8b949e# Save to flash

Te6edf3captureTb4b4b4(Te6edf3resolutionTff7b72=Ta5d6ff"Ta5d6ffcifTa5d6ff"Tb4b4b4, Te6edf3qualityTff7b72=T79c0ff30Tb4b4b4)

T8b949e# In-memory only (for LXMF transmission)

Te6edf3img_bytes Tff7b72= Te6edf3captureTb4b4b4(Te6edf3pathTff7b72=Tff7b72NoneTb4b4b4, Te6edf3resolutionTff7b72=Ta5d6ff"Ta5d6ffqvgaTa5d6ff"Tb4b4b4, Te6edf3qualityTff7b72=T79c0ff15Tb4b4b4)

Available resolutions: T383838qqvga (160 × 120), T383838qvga (320 × 240), T383838cif (400 × 296), T383838hvga (480 × 320), T383838vga (640 × 480), and several larger options.

A minimal LXMF client that boots, takes a reading, sends it to a fixed "hub" address, and goes back to deepsleep on a timer. Battery-friendly.

• Hardware: any supported ESP32-S3 + sensor (e.g. BME280 on I²C, SDS011 on UART).

• Firmware: standard MicroPython.

• Config: WiFi creds + T383838SENSOR_HUB = "<hex destination hash>" in T383838config.py (the LXMF address of your collector node — copy it from your collector's boot log or MeshChat).

• How to use: T383838import example_sensor. Save as T383838main.py for automatic restart-on-wake.

The deepsleep timer is set inside the example; change it to suit your duty cycle.

Turns an RP2040 with an attached LoRa radio (E32 or SX1262) into a transparent USB-to-Reticulum bridge — chat over LoRa from any laptop without installing MeshChat.

• Hardware: RP2040 (e.g. Waveshare RP2040-Zero) + a LoRa interface.

• Firmware: standard MicroPython for RP2040.

• Config: LoRa interface enabled in T383838CONFIG["interfaces"].

• How to use: plug the RP2040 into your laptop, open a serial terminal (T383838screen, T383838minicom, T383838tio, T383838PuTTY) on its USB CDC port. Type to chat.

Anything that doesn't start with T383838/ is sent as an LXMF chat message to the current target. The current target auto-switches to the most recent peer who messaged you, so replies are automatic.

Every interface is configured by an entry in the T383838CONFIG["interfaces"] list in T383838config.py. You can run multiple interfaces at the same time (e.g. WiFi + LoRa). The auto-generated T383838/rns/config.json on the device mirrors this — you usually don't need to edit it by hand.

The default. Broadcasts on the local LAN and pairs with MeshChat / Sideband automatically.

T282828

Ta5d6ff"Ta5d6fftypeTa5d6ff"Tb4b4b4: Ta5d6ff"Ta5d6ffUDPInterfaceTa5d6ff"Tb4b4b4,

Ta5d6ff"Ta5d6ffnameTa5d6ff"Tb4b4b4: Ta5d6ff"Ta5d6ffWiFi UDPTa5d6ff"Tb4b4b4,

Ta5d6ff"Ta5d6ffenabledTa5d6ff"Tb4b4b4: Tff7b72TrueTb4b4b4,

Ta5d6ff"Ta5d6fflisten_ipTa5d6ff"Tb4b4b4: Ta5d6ff"Ta5d6ff0.0.0.0Ta5d6ff"Tb4b4b4,

Ta5d6ff"Ta5d6fflisten_portTa5d6ff"Tb4b4b4: T79c0ff4242Tb4b4b4,

Ta5d6ff"Ta5d6ffforward_ipTa5d6ff"Tb4b4b4: Tff7b72NoneTb4b4b4, T8b949e# None = auto-detected subnet broadcast

Ta5d6ff"Ta5d6ffforward_portTa5d6ff"Tb4b4b4: T79c0ff4242Tb4b4b4,

Tb4b4b4}

HDLC-framed UART. Use this for an RNode device, a generic LoRa modem in transparent serial mode, or board-to-board wired links.

T282828

Ta5d6ff"Ta5d6fftypeTa5d6ff"Tb4b4b4: Ta5d6ff"Ta5d6ffSerialInterfaceTa5d6ff"Tb4b4b4,

Ta5d6ff"Ta5d6ffnameTa5d6ff"Tb4b4b4: Ta5d6ff"Ta5d6ffSerial LinkTa5d6ff"Tb4b4b4,

Ta5d6ff"Ta5d6ffenabledTa5d6ff"Tb4b4b4: Tff7b72TrueTb4b4b4,

Ta5d6ff"Ta5d6ffuart_idTa5d6ff"Tb4b4b4: T79c0ff2Tb4b4b4,

Ta5d6ff"Ta5d6fftx_pinTa5d6ff"Tb4b4b4: T79c0ff17Tb4b4b4,

Ta5d6ff"Ta5d6ffrx_pinTa5d6ff"Tb4b4b4: T79c0ff16Tb4b4b4,

Ta5d6ff"Ta5d6ffspeedTa5d6ff"Tb4b4b4: T79c0ff115200Tb4b4b4,

Tb4b4b4}

Native SPI talk to the SX1262 radio. No external serial module needed.

Prerequisite: install the LoRa driver on the device once:

T282828

Board pinout presets. The board's wiring (SPI + control pins, TCXO, regulator) lives in T383838firmware/lora_boards.py as named presets — you reference one with a T383838"board" key and keep only the network/radio parameters in the interface entry:

T282828

Ta5d6ff"Ta5d6fftypeTa5d6ff"Tb4b4b4: Ta5d6ff"Ta5d6ffLoRaInterfaceTa5d6ff"Tb4b4b4,

Ta5d6ff"Ta5d6ffboardTa5d6ff"Tb4b4b4: Ta5d6ff"Ta5d6ffesp32s3_cam_sx1262Ta5d6ff"Tb4b4b4, T8b949e# pinout preset (lora_boards.py)

Ta5d6ff"Ta5d6ffnameTa5d6ff"Tb4b4b4: Ta5d6ff"Ta5d6ffLoRa SX1262Ta5d6ff"Tb4b4b4,

Ta5d6ff"Ta5d6ffenabledTa5d6ff"Tb4b4b4: Tff7b72TrueTb4b4b4,

Ta5d6ff"Ta5d6fffreq_khzTa5d6ff"Tb4b4b4: T79c0ff868800Tb4b4b4,

Ta5d6ff"Ta5d6ffsfTa5d6ff"Tb4b4b4: T79c0ff8Tb4b4b4,

Ta5d6ff"Ta5d6ffbwTa5d6ff"Tb4b4b4: Ta5d6ff"Ta5d6ff125Ta5d6ff"Tb4b4b4,

Ta5d6ff"Ta5d6ffcoding_rateTa5d6ff"Tb4b4b4: T79c0ff5Tb4b4b4,

Ta5d6ff"Ta5d6fftx_powerTa5d6ff"Tb4b4b4: T79c0ff14Tb4b4b4,

Ta5d6ff"Ta5d6ffsyncwordTa5d6ff"Tb4b4b4: T79c0ff0x1424Tb4b4b4,

Tb4b4b4}

The pins are merged in at startup. Any pin set explicitly on the interface overrides the preset, so you can tweak one pin without editing T383838lora_boards.py.

Adding a board: add one entry to T383838LORA_BOARDS in T383838firmware/lora_boards.py with that board's T383838sck/mosi/miso/cs/busy/dio1/reset pins (plus T383838dio2_rf_sw, T383838dio3_tcxo_millivolts, and optionally T383838use_dcdc / T383838spi_baudrate), then point an interface at it by name. Radio params stay in T383838config.py so every node on the mesh shares them.

Radio parameters (interface entry — must match across the whole mesh)

• T383838freq_khz: 868000 (EU), 915000 (US), 923000 (AS).

• T383838sf: 7–12 (higher = longer range, slower).

• T383838bw: T383838"125" / T383838"250" / T383838"500" (lower = longer range, slower).

• T383838tx_power: -9 to +22 dBm.

• T383838syncword: T3838380x1424 — Reticulum/RNode-compatible.

• T383838dio2_rf_sw: T383838True on Wio-SX1262 (radio drives DIO2 as RF switch internally).

• T383838dio3_tcxo_millivolts: T3838381800 on Wio-SX1262 (TCXO). T383838None to disable (crystal-only modules).

• T383838lbt_rssi: CSMA/listen-before-talk busy threshold in dBm (default T383838-100, T383838None disables). Every frame TX first probes the channel and defers in short random slots while it's busy — same etiquette as RNode firmware, essential when a repeater shares the channel.

• T383838lbt_max_ms: max LBT wait before transmitting anyway (default T3838382000).

The receive path is also hardened against transparent repeaters (devices that re-transmit every frame verbatim): duplicate halves of split packets (>254 B) are detected and dropped instead of corrupting reassembly.

Transparent serial LoRa module (product page) with HDLC framing, AUX flow control, and optional auto-configuration of the module's hex registers.

T282828

Ta5d6ff"Ta5d6fftypeTa5d6ff"Tb4b4b4: Ta5d6ff"Ta5d6ffE32InterfaceTa5d6ff"Tb4b4b4,

Ta5d6ff"Ta5d6ffnameTa5d6ff"Tb4b4b4: Ta5d6ff"Ta5d6ffLoRa E32Ta5d6ff"Tb4b4b4,

Ta5d6ff"Ta5d6ffenabledTa5d6ff"Tb4b4b4: Tff7b72TrueTb4b4b4,

Ta5d6ff"Ta5d6ffuart_idTa5d6ff"Tb4b4b4: T79c0ff1Tb4b4b4,

Ta5d6ff"Ta5d6fftx_pinTa5d6ff"Tb4b4b4: T79c0ff4Tb4b4b4,

Ta5d6ff"Ta5d6ffrx_pinTa5d6ff"Tb4b4b4: T79c0ff5Tb4b4b4,

Ta5d6ff"Ta5d6ffspeedTa5d6ff"Tb4b4b4: T79c0ff9600Tb4b4b4,

Ta5d6ff"Ta5d6ffm0_pinTa5d6ff"Tb4b4b4: T79c0ff15Tb4b4b4,

Ta5d6ff"Ta5d6ffm1_pinTa5d6ff"Tb4b4b4: T79c0ff2Tb4b4b4,

Ta5d6ff"Ta5d6ffaux_pinTa5d6ff"Tb4b4b4: T79c0ff6Tb4b4b4,

Ta5d6ff"Ta5d6ffauto_configureTa5d6ff"Tb4b4b4: Tff7b72FalseTb4b4b4,

Ta5d6ff"Ta5d6fftimeoutTa5d6ff"Tb4b4b4: T79c0ff3000Tb4b4b4,

Ta5d6ff"Ta5d6ffchannelTa5d6ff"Tb4b4b4: T79c0ff6Tb4b4b4,

Ta5d6ff"Ta5d6ffair_rateTa5d6ff"Tb4b4b4: T79c0ff2Tb4b4b4,

Ta5d6ff"Ta5d6fftx_powerTa5d6ff"Tb4b4b4: T79c0ff3Tb4b4b4,

Tb4b4b4}

• T383838channel: freq = 862 + channel MHz. Channel 6 = 868 MHz (EU ISM), 60 = 922 MHz (US ISM).

• T383838air_rate: 0 = 300 bps, 1 = 1200, 2 = 2400 (default), 3 = 4800, 4 = 9600, 5 = 19200.

• T383838tx_power: 0 = 20 dBm, 1 = 17 dBm, 2 = 14 dBm, 3 = 10 dBm.

• T383838auto_configure: T383838True writes the channel/rate/power registers to the module's flash at boot. Set T383838False once the module is configured.

• T383838timeout: HDLC frame timeout in ms. Must be >2× the air time of a full packet. At 2400 bps a 182-byte announce takes ~760 ms, so 3000 ms is safe.

Pin gotcha: on RP2040, do not use UART1 alternate-function pins (GPIO 3, 6, 7, 8) for M0/M1 — UART1 init claims them for CTS/RTS/TX and the resulting contention can damage the GPIO drivers. The driver also sets M0/M1 to 12 mA drive strength (vs the 4 mA default) so the E32's internal pull-ups release reliably.

Power gotcha: the E32-900T20D draws ~120 mA at 20 dBm TX. On RP2040-Zero this current spike will crash the MCU even off the 5 V USB rail. Use T383838tx_power: 3 (10 dBm, ~40 mA) unless the E32 has its own supply with decoupling.

Connects to a remote RNS TCP transport server. HDLC framing, wire-compatible with reference Reticulum's T383838TCPServerInterface. Auto-reconnects on disconnect.

T282828

Ta5d6ff"Ta5d6fftypeTa5d6ff"Tb4b4b4: Ta5d6ff"Ta5d6ffTCPClientInterfaceTa5d6ff"Tb4b4b4,

Ta5d6ff"Ta5d6ffnameTa5d6ff"Tb4b4b4: Ta5d6ff"Ta5d6ffTransport HubTa5d6ff"Tb4b4b4,

Ta5d6ff"Ta5d6ffenabledTa5d6ff"Tb4b4b4: Tff7b72TrueTb4b4b4,

Ta5d6ff"Ta5d6fftarget_hostTa5d6ff"Tb4b4b4: Ta5d6ff"Ta5d6ffrn.example.comTa5d6ff"Tb4b4b4,

Ta5d6ff"Ta5d6fftarget_portTa5d6ff"Tb4b4b4: T79c0ff4243Tb4b4b4,

Tb4b4b4}

Add T383838networkname and/or T383838passphrase to any interface to require authentication. Both sides must use identical values.

T282828

Ta5d6ff"Ta5d6fftypeTa5d6ff"Tb4b4b4: Ta5d6ff"Ta5d6ffTCPClientInterfaceTa5d6ff"Tb4b4b4,

Ta5d6ff"Ta5d6ffnameTa5d6ff"Tb4b4b4: Ta5d6ff"Ta5d6ffAuthenticated TCPTa5d6ff"Tb4b4b4,

Ta5d6ff"Ta5d6ffenabledTa5d6ff"Tb4b4b4: Tff7b72TrueTb4b4b4,

Ta5d6ff"Ta5d6fftarget_hostTa5d6ff"Tb4b4b4: Ta5d6ff"Ta5d6ffrn.example.comTa5d6ff"Tb4b4b4,

Ta5d6ff"Ta5d6fftarget_portTa5d6ff"Tb4b4b4: T79c0ff4243Tb4b4b4,

Ta5d6ff"Ta5d6ffnetworknameTa5d6ff"Tb4b4b4: Ta5d6ff"Ta5d6ffmy_networkTa5d6ff"Tb4b4b4,

Ta5d6ff"Ta5d6ffpassphraseTa5d6ff"Tb4b4b4: Ta5d6ff"Ta5d6ffmy_secret_passphraseTa5d6ff"Tb4b4b4,

Tb4b4b4}

The optional T383838ifac_size (default 16 bytes) controls the IFAC tag length and must match the server.

Set T383838enable_transport: True and the node becomes a Reticulum transport router: it forwards traffic between its interfaces so a LoRa-only mesh reaches the wider network and back. It is wire-compatible with reference RNS — a µReticulum router can sit transparently in a path between reference RNS, MeshChat, Sideband or NomadNet nodes.

This is directed routing, not blind flooding: the node learns routes from announces and forwards each packet on the one correct interface toward its destination, extending range without saturating the mesh. example_transport_router.py is a ready-made LoRa ↔ WiFi/TCP router built on it.

T282828

Te6edf3CONFIG Tff7b72= Tb4b4b4{

Ta5d6ff"Ta5d6ffenable_transportTa5d6ff"Tb4b4b4: Tff7b72TrueTb4b4b4, T8b949e# this node relays for others

Ta5d6ff"Ta5d6ffinterfacesTa5d6ff"Tb4b4b4: Tb4b4b4[

Tb4b4b4{ Ta5d6ff"Ta5d6fftypeTa5d6ff"Tb4b4b4: Ta5d6ff"Ta5d6ffLoRaInterfaceTa5d6ff"Tb4b4b4, Tff7b72.Tff7b72.Tff7b72. Tb4b4b4}Tb4b4b4, T8b949e# the LoRa mesh side

Tb4b4b4{ Ta5d6ff"Ta5d6fftypeTa5d6ff"Tb4b4b4: Ta5d6ff"Ta5d6ffTCPClientInterfaceTa5d6ff"Tb4b4b4, Tff7b72.Tff7b72.Tff7b72. Tb4b4b4}Tb4b4b4, T8b949e# the IP side (rnsd / MeshChat); or a UDPInterface

Tb4b4b4]Tb4b4b4,

Tb4b4b4}

What it carries — everything, multi-hop, wire-compatible:

Routing state lives in RAM-bounded tables: T383838path_table (dest → next-hop + interface + hop count), T383838reverse_table (proof return), T383838link_table (link/resource transit), plus a small cache of recent announces.

Choosing between equal paths — when the same announce reaches a node over two interfaces at the same hop count, whichever copy arrived first would otherwise keep the path forever. Set T383838gravity on an interface to express a preference (RNS 1.4.1 semantics: higher wins, T3838380 is neutral, negatives discouraged). T383838default_gravity at the top level applies to every interface that does not set its own.

T282828

Te6edf3CONFIG Tff7b72= Tb4b4b4{

Ta5d6ff"Ta5d6ffdefault_gravityTa5d6ff"Tb4b4b4: T79c0ff0Tb4b4b4,

Ta5d6ff"Ta5d6ffinterfacesTa5d6ff"Tb4b4b4: Tb4b4b4[

Tb4b4b4{ Ta5d6ff"Ta5d6fftypeTa5d6ff"Tb4b4b4: Ta5d6ff"Ta5d6ffTCPClientInterfaceTa5d6ff"Tb4b4b4, Ta5d6ff"Ta5d6ffgravityTa5d6ff"Tb4b4b4: T79c0ff5Tb4b4b4, Tff7b72.Tff7b72.Tff7b72. Tb4b4b4}Tb4b4b4, T8b949e# prefer IP when both work

Tb4b4b4{ Ta5d6ff"Ta5d6fftypeTa5d6ff"Tb4b4b4: Ta5d6ff"Ta5d6ffLoRaInterfaceTa5d6ff"Tb4b4b4, Ta5d6ff"Ta5d6ffgravityTa5d6ff"Tb4b4b4: T79c0ff0Tb4b4b4, Tff7b72.Tff7b72.Tff7b72. Tb4b4b4}Tb4b4b4, T8b949e# fall back to radio

Tb4b4b4]Tb4b4b4,

Tb4b4b4}

Gravity only breaks ties. It never buys a longer path — a shorter route always wins first, regardless of preference.

Resilience (built for an open, long-running mesh): routing tables expire and are purged when an interface drops (WiFi-flap recovery); per-source announce rate-limiting and hard table caps prevent runaway memory; optional strict link-proof validation (native-gated Ed25519, ~17 ms); blackholing of misbehaving identities; and the path table persists to flash so a reboot isn't a mesh blackout.

Watching it work: every forward logs a T383838Relay … line at T383838NOTICE and bumps a counter, so you can follow relay activity in the console. The router example also serves a plain-HTTP dashboard on the LAN (webmonitor.py) showing live T383838RELAYED ann/data/link/proof counts, the path table, and the log stream. Path-table rows are labeled with the peer's announced display name and the protocol behind each destination hash — T383838lxmf (messaging peer), T383838lxmf-pn (propagation node), T383838nomad (NomadNet pages), T383838voice-lxst / T383838voice-mc (LXST and MeshChat call endpoints), T383838probe, or a T383838?hex tag for unknown apps. Classification reads the T383838name_hash every announce carries (no decryption involved) and survives reboots by recomputing labels from persisted identities.

Running it headless: a transport router usually runs without a USB cable, so it wants WiFi up at boot and a way back in to control it. boot.py can bring up WiFi + WebREPL automatically on every reset — but it ships commented out, so a plain leaf node (LoRa-only, sensor, proxy) boots straight to the REPL instead of sitting through a needless ~15 s WiFi connect. Uncomment the execution block at the bottom of T383838boot.py only on a transport node; you can then reach it at T383838ws://<node-ip>:8266/ (log in with T383838WEBREPL_PASSWORD from T383838config.py) to start/stop the router and push fixes over the air.

│ A transport router wants the RAM headroom of an ESP32-S3 (PSRAM is ideal). Forwarding is

│ single-instance (no shared-instance or tunnel interfaces) — most useful as a LoRa ↔ IP gateway.

Expose a dedicated destination that replies to T383838rnprobe, the reference reachability/RTT tool. Useful for debugging transport paths.

T282828

Te6edf3CONFIG Tff7b72= Tb4b4b4{

Ta5d6ff"Ta5d6ffprobeTa5d6ff"Tb4b4b4: Tb4b4b4{

Ta5d6ff"Ta5d6ffenabledTa5d6ff"Tb4b4b4: Tff7b72TrueTb4b4b4,

Ta5d6ff"Ta5d6ffapp_nameTa5d6ff"Tb4b4b4: Ta5d6ff"Ta5d6ffurnsTa5d6ff"Tb4b4b4, T8b949e# full_name = "urns.probe"

Ta5d6ff"Ta5d6ffaspectTa5d6ff"Tb4b4b4: Ta5d6ff"Ta5d6ffprobeTa5d6ff"Tb4b4b4,

Ta5d6ff"Ta5d6ffannounce_intervalTa5d6ff"Tb4b4b4: T79c0ff60 Tff7b72* T79c0ff60Tb4b4b4, T8b949e# 1 hour; 0 = announce once at boot only

Tb4b4b4}Tb4b4b4,

Ta5d6ff"Ta5d6ffinterfacesTa5d6ff"Tb4b4b4: Tb4b4b4[Tff7b72.Tff7b72.Tff7b72.Tb4b4b4]Tb4b4b4,

Tb4b4b4}

When enabled the boot log prints the destination hash and full name:

T282828

From a desktop with reference RNS installed:

T282828

Both T383838full_name and T383838destination_hash are required: announces only carry a hash of the name, so the dot-name has to be known out of band. A successful probe prints T383838Valid reply received from <hash> with the measured RTT. The probe destination refuses link requests — it only signs PROOF replies. Other apps filter it out of their UIs by app_name.

A LoRa-only node has no WiFi/NTP and no battery-backed RTC, so its clock sits at T3838382000-01-01 and every message/announce it sends is stamped January 2000 (you'll see this on received images in MeshChat). Time sync fixes this by learning the real time from the mesh itself — every announce and every signed LXMF message already carries the sender's Unix timestamp.

T282828

Te6edf3CONFIG Tff7b72= Tb4b4b4{

Ta5d6ff"Ta5d6fftime_syncTa5d6ff"Tb4b4b4: Tb4b4b4{

Ta5d6ff"Ta5d6ffenabledTa5d6ff"Tb4b4b4: Tff7b72TrueTb4b4b4,

Ta5d6ff"Ta5d6fftrusted_nodesTa5d6ff"Tb4b4b4: Tb4b4b4[Tb4b4b4]Tb4b4b4, T8b949e# see modes below

Ta5d6ff"Ta5d6ffmin_sourcesTa5d6ff"Tb4b4b4: T79c0ff2Tb4b4b4, T8b949e# corroboration quorum (when trusted_nodes is empty)

Ta5d6ff"Ta5d6fftoleranceTa5d6ff"Tb4b4b4: T79c0ff120Tb4b4b4, T8b949e# seconds of allowed disagreement between peers

Tb4b4b4}Tb4b4b4,

Ta5d6ff"Ta5d6ffinterfacesTa5d6ff"Tb4b4b4: Tb4b4b4[Tff7b72.Tff7b72.Tff7b72.Tb4b4b4]Tb4b4b4,

Tb4b4b4}

Two modes:

• Authority — list one or more LXMF delivery hashes (hex, exactly as shown in MeshChat/Sideband) in T383838trusted_nodes. The first announce or signed message from a matching node sets the clock. Fastest, and corrects time on the very first packet heard.

• Corroboration — leave T383838trusted_nodes empty. The clock is set only once T383838min_sources distinct peers agree on the time within T383838tolerance seconds (the median is applied). No single node can move your clock, so you don't have to trust anyone in particular.

The sync runs once per power-on, only while the clock is still unset — it never re-adjusts mid-session. A reboot resets the RTC to 2000, and the node re-syncs from the next qualifying packet. After syncing, both outgoing message timestamps and announce timestamps are correct for the rest of the session.

The moment the clock syncs, the node automatically re-announces all its destinations: announces sent before sync carry a year-2000 emission timestamp and are rejected as stale replays by peers that knew the node from a previous boot — without the re-announce, a rebooted node would stay invisible to the mesh until its next periodic announce.

│ The ESP32's internal RTC keeps time only while powered — it does not survive a full power cycle.

│ For instant-correct time at boot with no peer audible, add a battery-backed RTC (e.g. DS3231 over

│ I²C).

Modular hardware drivers in T383838firmware/peripherals/ with a uniform contract:

• T383838init(...) — set up hardware

• T383838process(content) — handle an LXMF message or page-template query, return a response string or T383838None

Peripherals are initialized at the top of T383838example_nomadnet_node.py (or T383838example_node.py). Uncomment what you have:

T282828

Tff7b72from T7ee787machine Tff7b72import Te6edf3PinTb4b4b4, Te6edf3SoftI2C

Te6edf3i2c Tff7b72= Te6edf3SoftI2CTb4b4b4(Te6edf3sclTff7b72=Te6edf3PinTb4b4b4(T79c0ff6Tb4b4b4)Tb4b4b4, Te6edf3sdaTff7b72=Te6edf3PinTb4b4b4(T79c0ff5Tb4b4b4)Tb4b4b4, Te6edf3freqTff7b72=T79c0ff100000Tb4b4b4)

Tff7b72import T7ee787peripheralsT7ee787.T7ee787bme280_sensor Tff7b72as T7ee787bme_sensor

Te6edf3bme_sensorTff7b72.Td2a8ffinitTb4b4b4(Te6edf3i2cTb4b4b4)

T8b949e# import peripherals.neopixel_led as neopixel_led

T8b949e# neopixel_led.init(pin=21)

T8b949e# import peripherals.gpio_control as gpio

T8b949e# gpio.init({"lamp": (2, "OUT")})

T8b949e# Battery: board-declared. Reads automatically IF the active board's preset in

T8b949e# lora_boards.py has a "battery" block. The XIAO ESP32-S3 has no BAT->ADC path

T8b949e# (Meshtastic disables battery on it too), so this stays off on that board.

Tff7b72import T7ee787peripheralsT7ee787.T7ee787adc_reader Tff7b72as T7ee787adc_reader

Tff7b72from T7ee787lora_boards Tff7b72import Te6edf3battery_config

Te6edf3_battery Tff7b72= Te6edf3battery_configTb4b4b4(Te6edf3CONFIGTb4b4b4)

Tff7b72if Te6edf3_batteryTb4b4b4:

Te6edf3adc_readerTff7b72.Td2a8ffinitTb4b4b4(Tb4b4b4{Ta5d6ff"Ta5d6ffbatteryTa5d6ff"Tb4b4b4: Te6edf3_batteryTb4b4b4[Ta5d6ff"Ta5d6ffpinTa5d6ff"Tb4b4b4]Tb4b4b4}Tb4b4b4, Te6edf3dividersTff7b72=Tb4b4b4{Ta5d6ff"Ta5d6ffbatteryTa5d6ff"Tb4b4b4: Te6edf3_batteryTff7b72.Td2a8ffgetTb4b4b4(Ta5d6ff"Ta5d6ffdividerTa5d6ff"Tb4b4b4, T79c0ff1.0Tb4b4b4)Tb4b4b4}Tb4b4b4)

T8b949e# import peripherals.sds011_sensor as sds011_sensor

T8b949e# sds011_sensor.init(uart_id=1, tx_pin=43, rx_pin=44)

Te6edf3active_peripherals Tff7b72= Tb4b4b4[Te6edf3bme_sensorTb4b4b4] Tff7b72+ Tb4b4b4(Tb4b4b4[Te6edf3adc_readerTb4b4b4] Tff7b72if Te6edf3_battery Tff7b72else Tb4b4b4[Tb4b4b4]Tb4b4b4)

Battery voltage is treated as board-fixed wiring: declare it once in the board's preset in T383838lora_boards.py as T383838"battery": {"pin": 1, "divider": 2.0} (the ADC GPIO and the T383838vbat = vpin × divider ratio), and T383838adc_reader picks it up automatically — T383838battery_config(CONFIG) resolves it and an inline T383838CONFIG["battery"] overrides. Boards with no battery→ADC path simply omit the block. Note: the Seeed XIAO ESP32-S3 (including the Wio-SX1262 "Meshtastic" kit) has no such path — there's no onboard divider, and Meshtastic itself ships that board with battery monitoring disabled (T383838BATTERY_PIN -1). So battery stays off unless you solder your own divider (T383838BAT+ → 2×200 kΩ → T383838GND, midpoint to A0/GPIO1) and add the block with T383838divider: 2.0.

The SDS011 also needs T383838sds011_sensor.start() inside the async event loop (see T383838run_with_announce() in the example files) — that schedules a 5-minute duty cycle so the fan only runs during measurement.

The SDS011 needs 5 V power (VUSB, only available with USB-powered boards). Its UART TX is 3.3 V-safe — no level shifter needed.

Active peripherals are also queried for the T383838{sensor} template variable in NomadNet pages. When multiple peripherals are active, all readings are shown.

• Double-check T383838WIFI_SSID / T383838WIFI_PASS in T383838config.py. The ESP32-S3 only supports 2.4 GHz networks — a 5 GHz-only SSID will fail silently.

• Some routers separate 2.4 / 5 GHz under the same SSID; explicitly join the 2.4 GHz one if your router offers it.

• The desktop running MeshChat and the µReticulum node must be on the same LAN subnet for UDP broadcast to reach across.

• If you have multiple NICs on the desktop (VPN, Docker bridge, virtual adapters), MeshChat may bind the wrong one. Disable interfaces you don't need.

• The example disables the WiFi access-point interface (T383838AP_IF) and turns WiFi power-management off — both are required to receive broadcasts. If you've stripped that out of T383838example_node.py, put it back.

• Run T383838mpremote mip install lora-sx126x lora-sync once. This installs the SX126x driver from T383838micropython-lib to the device.

• The T383838.mpy file in T383838firmware/lib/ must match your architecture: T383838*_xtensawin.mpy for ESP32-S3, T383838*_armv6m.mpy for RP2040.

• The T383838.mpy format is tied to a MicroPython version range. If your MicroPython is much newer than 1.22, see BUILDING_NATIVE_MODULES.md to rebuild.

• The system still works without the native module — just at ~4 s per message instead of <200 ms.

• Both ends must share T383838freq_khz, T383838sf, T383838bw, T383838coding_rate, and T383838syncword. A single mismatch and you'll receive nothing.

• For SX1262 boards with a TCXO (Wio-SX1262), T383838dio3_tcxo_millivolts must be set or the radio fails to init with T383838OpError 0x20.

• For SX1262 boards in TX-but-no-output situations, check the regulator mode and TX power. The T-Deck v1 specifically needs DC-DC regulator mode (see reticulum-tdeck for the workaround).

• The E32 draws ~120 mA at 20 dBm and that current spike can brown out the RP2040. Use T383838tx_power: 3 (10 dBm) or give the E32 its own supply with decoupling caps.

• Usually a WiFi-stack issue from too many open sockets after long uptime. Reset the board.

• You're running standard MicroPython. The camera example requires the camera-enabled build — see Step 1.

Tested and confirmed working with:

• MeshChat — bi-directional announces, opportunistic messaging, delivery receipts

• Sideband — peer discovery, LXMF messaging

• NomadNet — peer discovery, LXMF messaging, page serving over Links

• Reference Reticulum (Python) — wire-compatible packets, announces, encryption, link handshake

• Reference LXMF — cross-validated message packing/unpacking, signature verification

• RNode (SX1276 / SX1278) — bidirectional LoRa, full split-packet support for the complete 500-byte MTU. Tested with Heltec Wireless Stick Lite V1 on 868 MHz.

• RNS transport servers — TCP client connectivity to remote transport hubs, automatic path learning from announces

Protocol behaviour tracks reference RNS 1.5.2. The 1.3.9 link and resource

safeguards are implemented here (see the Resource and link safeguards block

under Protocol details), as is the whole of 1.4.x that

applies to a leaf or relay node: dynamic link path re-balancing, interface

gravity, RTT-scaled keepalive and stale windows with the keepalive-reply

throttle, T383838max_request_size / T383838max_response_size, and out-of-window rejection

on T383838Channel (see Link path re-balancing below). Neither 1.4.x nor 1.5.x

changed the wire format, so older and newer peers interoperate either way.

RNS 1.5.0's headline is a priority-based inbound ingress-queue rewrite of

T383838Transport, built on OS threads and locks — there is no analogue for this

single-threaded T383838uasyncio port, and none is needed for interop: the port

already prioritises inline data, proof and link traffic over deferred announce

validation. The two items from that release that apply to a leaf or relay node

are implemented: an excessive-hop-count drop (T383838PATHFINDER_M = 128, rejected in

T383838Transport.packet_filter) and a constant-time HMAC comparison in

T383838Token.verify_hmac. Identity blackholing is supported (T383838Transport.blackhole());

the operator blackhole publish/subscribe lists and everything surfaced only

through T383838rnstatus are out of scope or opt-in, and none of it affects

interoperability.

RNS 1.5.1 and 1.5.2 likewise changed no wire format. Both are dominated by work

with no analogue on a single-threaded MCU — adaptive dataplane ingress/egress

control layered on the 1.5.0 queue rewrite, T383838BackboneInterface transmit

buffers, live profiling, and T383838rnstatus diagnostics — or by fixes already

covered here (the 1.5.2 resource-cancel guard cannot occur, since cancellation

routes through T383838resource_concluded and the link's T383838cancel_*_resource already

check membership; bz2 compression already falls back to uncompressed). The two

frame-validation hardening checks that apply to a leaf or relay node are

implemented: T383838Packet.unpack rejects a zero-length data field, and

T383838Transport.packet_filter drops an announce frame larger than the MTU.

Out of scope for an MCU port: T383838BackboneInterface flap-blocking, interface

discovery, I2P, shared-instance/tunnel interfaces, and the T383838rnsh utility.

│ If you run an T383838rnsh listener (any platform), update it to RNS 1.3.9: that release patches a

│ critical vulnerability where a command could be started on a session that never completed

│ identity authorisation. This port contains no listener, so it is not affected — but a listener

│ elsewhere on your mesh is.

The native C module (Monocypher-based) is ~160× faster than pure-Python Curve25519. Pre-built T383838.mpy files for ESP32-S3 and RP2040 ship in T383838firmware/lib/ — they're loaded automatically when present. If you accidentally don't upload them, everything still works, just slowly.

• MicroPython only — no CPython/desktop support. Uses T383838uhashlib, T383838ucryptolib, T383838uasyncio, T383838micropython.const directly.

• LXMF message size — single-packet opportunistic messages up to ~295 bytes content. Larger messages (up to 16 KB) use Link-based DIRECT delivery via Resource transfer, including through multi-hop transport chains.

• No propagation node — cannot store-and-forward messages for offline peers.

• On-demand path resolution — when sending to a peer it has no route to (e.g. a transport-distant node right after a reboot), the node issues a Reticulum path request and delivers the message once the route is learned, instead of silently dropping it. Replies also reuse an already-open link when present.

• Pure-Python crypto fallback — ~4 s message round-trip without the native module. With native module: <200 ms.

Potential areas for expansion:

• Propagation node — store-and-forward for offline peers

• More sensor integrations — additional peripheral drivers

This section is the deep dive — you don't need any of it to use the project, but it's here for anyone interested in how it interoperates with reference Reticulum.

<details>

<summary><b>Message flow (MeshChat → ESP32-S3)</b></summary>

T282828

</details>

<details>

<summary><b>LXMF wire format</b></summary>

Total overhead: 112 bytes. Content capacity in a single encrypted packet: ~295 bytes.

Announces carry msgpack-encoded app data so peers know the node's display name:

T282828

T8b949e# Example: [b"ESP32s3", None]

Ta5d6ffbTa5d6ff'Tffea00\x92Tffea00\xc4Tffea00\x07Ta5d6ffESP32s3Tffea00\xc0Ta5d6ff'

</details>

<details>

<summary><b>NomadNet link handshake</b></summary>

T282828

Each link consumes ~350 bytes of RAM. Up to 4 concurrent links are supported (T383838MAX_ACTIVE_LINKS=4). Idle links are cleaned up after 12 minutes.

</details>

<details>

<summary><b>Outbound link establishment on half-duplex LoRa (LRRTT resend + delivery retry)</b></summary>

Reference RNS marks a responder link established — and starts accepting resource

transfers on it — only when the initiator's RTT packet (LRRTT) arrives. That

packet is sent exactly once, and on a half-duplex LoRa mesh it is unusually easy to

lose: a node typically opens its reply link seconds after proving an inbound

message, while the relay upstream is still transmitting the sibling link's traffic —

its radio is deaf mid-TX and the LRRTT dies. The failure is silent and deceptive:

the half-established peer still answers keepalives (raw 1-byte frames, processed

regardless of link state) but discards every resource advertisement, so the link

looks alive while nothing ever delivers.

µReticulum hardens both layers on the initiator side:

• LRRTT resend (T383838link.py) — the RTT payload is kept and re-sent (up to 4×,

every 4 s) until the peer sends anything that decrypts, which proves its side

of the link completed establishment (each resend re-encrypts with a fresh IV, so

transport dedup never drops it; a peer that was already established just re-fires

its idempotent established-callback).

• DIRECT delivery retry (T383838lxmf.py) — if the link dies before the message got

through (establishment timeout: lost LR or proof) or the resource transfer fails,

the delivery is re-attempted on a fresh link, 3 attempts total — matching

reference LXMF's retry behavior.

</details>

<details>

<summary><b>Resource and link safeguards (parity with RNS 1.3.9)</b></summary>

A link peer is untrusted input: it can send a malformed resource advertisement,

re-identify mid-session, or vanish mid-transfer. Reference RNS 1.3.9 tightened

these paths, and this port implements the equivalents — with an MCU's much

smaller margin for error in mind.

• Advertisement validation — every advertisement is parsed and validated

inside one guarded block: msgpack errors, missing fields, wrong types,

negative or absurd sizes are rejected before anything is allocated. On a

desktop an unchecked size claim wastes memory; on an ESP32 it is an immediate

out-of-memory. An advertisement that cannot be processed at all tears the link

down rather than leaving it looping on bad input.

• Pre-send link check — a resource verifies its link is still T383838ACTIVE

before every advertisement, part, request and proof. A closing link nulls its

resources' references, so an unguarded watchdog send would raise inside the

event loop.

• Cancellation signalling — cancelling tells the peer: T383838RESOURCE_ICL from

the sender, T383838RESOURCE_RCL from the receiver (the receiver-side signal is new

in 1.3.9). Without it the far end keeps re-advertising or re-requesting until

its own timeout — minutes of wasted airtime on half-duplex LoRa. A cancel that

arrives from the peer is never echoed back.

• Identity binds once — a second T383838identify on an established link is

ignored, so anything authorising on the identified identity cannot have its

authorisation subject swapped mid-session.

• HDLC frame validation (TCP interface) — frames shorter than a packet

header, or that overflowed the buffer mid-flight, are dropped instead of

handed to routing as truncated packets.

Covered by T383838firmware/tests/test_resource_safeguards.py.

</details>

<details>

<summary><b>Link path re-balancing and keepalives (parity with RNS 1.4.x)</b></summary>

A link request and the proof that answers it do not always travel the same

number of hops — a route can shorten or lengthen between the two, and on a mesh

with several possible paths they can simply differ. Both ends check the proof's

hop count, so a mismatch used to mean the link never came up at all.

• Re-balancing at a relay — when a transit link-request proof arrives with a

hop count other than the one recorded for that link, the relay verifies the

proof signature and then adopts the new count, in both the link table and the

path table, instead of dropping the proof. The signature check is mandatory

here: this rewrites routing state, so an unverifiable proof (no native

Ed25519, or T383838strict_lr_validation off) is still dropped — a failed link beats

an unauthenticated hop rewrite.

• Re-balancing at the initiator — the same correction is applied to the path

table once our own link goes active. No extra crypto is spent: the link only

reaches that state after the peer's signature over our link id has been

verified.

• Keepalive on outbound silence — what stales a link at the far end is how

long since we transmitted, not how long since we heard. An initiator that

only receives (a peer streaming to it) used to fall silent and get torn down

mid-stream; it now probes when either direction has been quiet.

• RTT-scaled windows — the RTT the initiator measures is carried in the

handshake and now sizes the receiver's keepalive and stale windows

(T383838clamp(rtt × 360/1.75, 5, 360), stale = twice that). LoRa clamps back to the

360 s / 720 s pair this port used unconditionally before; a fast link drops to

roughly 20 s / 41 s, so a dead TCP link is reaped in under a minute instead of

twelve. An absent or unusable value keeps the old defaults.

• Keepalive reply throttle — with both ends deriving that window from the

same RTT, a T3838380xFF probe is answered only if we have been quiet for it.

Anything transmitted inside the window already proved us alive, and on

half-duplex LoRa the saved frame is one that would have gone out exactly when

the channel is busiest.

• Channel window — a message sequence past the far edge of the receive

window is rejected rather than buffered forever behind a gap that can never be

filled.

Request and response size limits — T383838destination.set_max_request_size(n)

caps what a destination's request handlers will accept, and

T383838link.request(..., max_response_size=n) caps what comes back. Both refuse

before buffering: an oversized single-packet request is dropped before it is

unpacked, and an oversized resource is cancelled with an T383838RCL before a single

part transfers, so the sender stops immediately rather than retrying for

minutes. Without a limit the stack's own 16 KB T383838MAX_RESOURCE_SIZE ceiling still

applies — worth lowering on a node with tens of KB of free heap, especially over

TCP where the negotiated link MTU reaches 16 KB.

Covered by T383838firmware/tests/test_transport.py, T383838test_link_request.py,

T383838test_resource_safeguards.py and T383838test_channel.py, and verified on an ESP32-S3

(T-Deck) against real native Ed25519.

</details>

<details>

<summary><b>SX1262 LoRa — RNode split-packet protocol</b></summary>

The LoRa interface implements the same split-packet framing as RNode firmware, enabling transparent interop with RNode devices and support for Reticulum's full 500-byte MTU over LoRa's 255-byte frame limit.

Every LoRa frame carries a 1-byte RNode header:

• Single frame (data ≤ 254 bytes): T383838[header] [data] — max 255 bytes

• Split packet (data 255–508 bytes): two frames with the same header byte (same sequence + FLAG_SPLIT), back-to-back:

• Frame 1: T383838[header] [first 254 bytes] = 255 bytes

• Frame 2: T383838[header] [remaining bytes]

The receiver matches split frames by sequence number and reassembles them into a complete Reticulum packet. Stale fragments are discarded after 15 seconds.

The T383838lora-sx126x MicroPython driver sends and receives bytes faithfully — the RNode header byte is the first byte returned by T383838poll_recv() on RX and the first byte written by T383838send() on TX. No FIFO offset workarounds are needed.

Packets with bit 7 set in the Reticulum flags byte (IFAC-tagged) are validated if IFAC is configured on the receiving interface, or dropped if IFAC is not configured. This matches reference Reticulum behavior.

</details>

<details>

<summary><b>ESP32-S3 socket workarounds</b></summary>

The UDP interface includes several workarounds for ESP32-S3 MicroPython lwIP quirks:

• Single TX/RX socket — saves ~280 bytes IDF heap vs two sockets.

• T383838settimeout(0) re-asserted after every T383838sendto() — ESP32-S3 lwIP bug: T383838sendto() corrupts the socket's non-blocking state. Without this, T383838recvfrom() silently blocks after the first send, freezing the async event loop.

• No T383838select.poll() — T383838poll(0) doesn't reliably detect incoming UDP on ESP32-S3 lwIP. Uses direct non-blocking T383838recvfrom() + T383838except OSError instead.

• RX socket watchdog — if the interface previously received traffic but hasn't for 60 seconds, the socket is closed and recreated.

• WiFi power management disabled — T383838wlan.config(pm=0) is required to receive broadcast UDP packets.

• AP_IF deactivated — dual-interface mode routes broadcast packets to AP instead of STA, preventing UDP broadcast reception.

</details>

<details>

<summary><b>Native crypto module (.mpy details)</b></summary>

The native C module wraps Monocypher compiled to native machine code, distributed as a T383838.mpy file alongside the Python code (no firmware recompile needed).

T383838.mpy files are version 6 (MicroPython 1.19+) and architecture-specific:

Both ship pre-built in T383838firmware/lib/ and are loaded automatically. If a future MicroPython version changes the T383838.mpy format, see BUILDING_NATIVE_MODULES.md for cross-compilation instructions.

</details>

<details>

<summary><b>Native BZ2 module</b></summary>

Reference RNS always compresses Resource transfers with bz2. The native C module provides both compression and decompression, producing stdlib-compatible bz2 output that interoperates with reference RNS.

• Decompression: ~100× faster than pure Python (~2 ms vs ~200 ms for 1 KB). Falls back to pure Python if native module is missing.

• Compression: ~500 ms for 1 KB on ESP32-S3. Reduces text payloads by 60–80% (e.g. 1 253 B → 394 B). Only available with native module — without it, Resources are sent uncompressed (which is valid).

</details>

T282828

MIT

Built on the Reticulum protocol by Mark Qvist. The pure-Python Curve25519 implementation is derived from pure25519 by Brian Warner.